home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / games / pinfo.zoo / pinfo_ti.txt < prev    next >
Text File  |  1992-12-01  |  33KB  |  859 lines
  1.  
  2.  
  3.  
  4. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  5.  
  6.  
  7. NAME
  8.        pinfo_ti  -  Description  of  the terminal interface to the portable
  9.        Infocom datafile interpreter.
  10.  
  11. SYNOPSIS
  12.        #include <stdio.h>
  13.        #include "infocom.h"
  14.  
  15.        extern gflags_t gflags;
  16.        extern char     *ti_location;
  17.        extern char     *ti_status;
  18.  
  19.  
  20.        const char *scr_usage;
  21.        const char *scr_long_usage;
  22.        const char *scr_opt_list;
  23.  
  24.        int scr_cmdarg( int argc, char ***argv_p );
  25.  
  26.        int scr_getopt( int c, const char *arg );
  27.  
  28.        void scr_setup( int margin,
  29.                        int indent,
  30.                        int lines,
  31.                        int context );
  32.  
  33.        void scr_begin();
  34.  
  35.        void scr_putline( const char *buffer );
  36.  
  37.        void scr_putscore();
  38.  
  39.        void scr_putsound( int number,
  40.                           int action,
  41.                           int volume,
  42.                           int argc );
  43.  
  44.        void scr_putmesg( const char *buffer, Bool is_error );
  45.  
  46.        int scr_getline( const char *prompt,
  47.                         int length,
  48.                         char *buffer );
  49.  
  50.        void scr_window( int size );
  51.  
  52.        void scr_set_win( int win );
  53.  
  54.        FILE *scr_open_sf( int length, char *buffer, int type );
  55.  
  56.        void scr_close_sf( const char *buffer, FILE *fp, int is_save );
  57.  
  58.        void scr_end();
  59.  
  60.        void scr_shutdown();
  61.  
  62.  
  63.  
  64. Revision 3.0                    21 October 1992                               1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  71.  
  72.  
  73. DESCRIPTION
  74.        These routines form  the  interface  between  the  portable  Infocom
  75.        datafile  interpreter  (pinfocom) and a particular type of terminal.
  76.        The pinfocom package comes with interfaces to the following terminal
  77.        types:
  78.  
  79.        termcap
  80.               This terminal type supports all(?) UNIX systems via an inter-
  81.               face to either termcap or terminfo  terminal  capability  and
  82.               either  termio,  termios,  or  sgtty line discipline control.
  83.               Optional support for the GNU readline line editing  and  his-
  84.               tory library is also available.
  85.  
  86.        amiga  This  terminal  type  supports  an Amiga interface, including
  87.               sound  and  command  line  editing.   See  amiga.c  for  full
  88.               details.
  89.  
  90.        msdos  This  terminal  type  supports  MS-DOS  based  systems.   See
  91.               msdos.c for full details.
  92.  
  93.        stream This terminal type should support any system with  a  C  com-
  94.               piler;  it  uses simple C stdio routines that all C libraries
  95.               will have.  Nothing fancy, but it works.
  96.  
  97.        Also in the works is an X11-based interface.
  98.  
  99.        This man page describes the interface between the pinfo  interpreter
  100.        and  the  terminal  support  packages so that programmers can create
  101.        their own interfaces to new systems.   Terminal  interface  will  be
  102.        abbreviated to TI below.
  103.  
  104.    Environment
  105.        The  interpreter  operates in two modes: game-playing mode (default)
  106.        and information mode (if any of the command-line options -h, -o, -O,
  107.        -v  and/or  -V are given), where the game is not played but informa-
  108.        tion about it is instead displayed on the screen.
  109.  
  110.        All input and output in game-playing mode is done  via  the  scr_*()
  111.        functions  described  below.   Output during information mode is via
  112.        simple C stdio library functions.
  113.  
  114.        The only interface between the interpreter and the terminal handling
  115.        code  is through the functions and global variables described below;
  116.        no other symbols in the TI code should be externally visible and any
  117.        other  external  symbols  in  the  interpreter  code  are subject to
  118.        change.
  119.  
  120. GENERAL
  121.        Some general issues to be considered:
  122.  
  123.    Asynchronous Events
  124.        The interpreter registers a signal handler for the SIGINT signal and
  125.        sets to ignore the SIGQUIT signal (if defined).
  126.  
  127.  
  128.  
  129.  
  130. Revision 3.0                    21 October 1992                               2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  137.  
  138.  
  139.        Any  other  signals or other asynchronous events are free to be han-
  140.        dled by the TI as it sees fit.  Note, however, that  none  of  these
  141.        handler  routines  may  modify  or access any interpreter variables:
  142.        interpreter variables listed below are only guaranteed to  be  valid
  143.        when  one  of  the  scr_*() functions below has been properly called
  144.        from within the interpreter code.
  145.  
  146.    Proportional Fonts
  147.        If the TI supports multiple fonts it is perfectly reasonable to  use
  148.        proportional-width fonts for printing general game text if you wish.
  149.  
  150.        However, at  certain  points  in  the  game  fixed-width  fonts  are
  151.        required,  such  as  when  printing  maps, etc.  To accomodate this,
  152.        before printing to  the  screen  scr_putline()  (see  below)  should
  153.        invoke  the  macro  F2_IS_SET(B_FIXED_FONT).   If this macro returns
  154.        non-0 then the current buffer should be  printed  in  a  fixed-width
  155.        font;  if it returns 0 then a proportional-width font may be used if
  156.        desired.
  157.  
  158.    Scripting
  159.        All Infocom games support the script command, which is  supposed  to
  160.        begin  a transcript of the user's adventure.  Normally this initial-
  161.        ized the printer and all subsequent text and commands  were  printed
  162.        to the printer as well as to the screen.
  163.  
  164.        The  TI  may support this feature as well.  There's no Z-Code primi-
  165.        tive for turning on and off scripting, however: instead  a  flag  is
  166.        set  or  reset.   In  scr_putline() and scr_getline() the macro call
  167.        F2_IS_SET(B_SCRIPTING) should be used; if it returns non-0 then  the
  168.        output  line  or  prompt and command should be printed to the script
  169.        file as well as the display.
  170.  
  171.        The interface will call scr_open_sf() with a file type of  SF_SCRIPT
  172.        when  a script file is to be opened and scr_close_sf() when a script
  173.        file is to be closed.
  174.  
  175.    Fixed Window
  176.        Only Seastalker makes use of the fixed window  feature  in  Standard
  177.        Series games, but it's nice to have nevertheless.
  178.  
  179.        If  the  TI  can  support  a  fixed window in addition to the normal
  180.        scrolling text window then scr_begin() should notify the interpreter
  181.        by calling F1_SETB(B_STATUS_WIN).  In this case the scr_window() and
  182.        scr_set_win()  functions  described  below  will  be  used  to  cre-
  183.        ate/manage/delete the fixed window.
  184.  
  185.        If  the TI cannot support a fixed window then the above macro should
  186.        not be called and scr_window() and scr_set_win() may be dummy  func-
  187.        tions.
  188.  
  189. GLOBAL VARIABLES
  190.        These  global  variables are defined in the interpreter code and may
  191.        be used by the TI:
  192.  
  193.  
  194.  
  195.  
  196. Revision 3.0                    21 October 1992                               3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  203.  
  204.  
  205.    gflags
  206.        Contains global flags and other general variables of interest.   The
  207.        only  field  which may be modified is the pr_status field, if the TI
  208.        doesn't support status line printing.
  209.  
  210.    ti_location
  211.        This nul-terminated string is a short  description  of  the  current
  212.        location of the player, for printing on the status line.  It is usu-
  213.        ally displayed on the left-hand side of the status line.
  214.  
  215.    ti_status
  216.        This nul-terminated  string  contains  the  status  of  the  player.
  217.        Depending  on  the game this may be score, score and turn number, or
  218.        the current time in a 12-hour clock.  This string is usually printed
  219.        on the right-hand side of the status line.
  220.  
  221.        These  global  variables  should  be defined in the TI .c file; they
  222.        will be declared exter